Past users, please read the section 'External Control' for important new features
The Problems:
What's going wrong in my AppleEvent routines?!?!?!?
The Solution:
AETracker!
AETracker is an INIT/CDev that allows you to log AppleEvent activity on your system. You can watch as much or as little AppleEvent manager (AEM) information as you like, and pull a little info or a lot of information about what's happening.
AETracker provides many levels of tracking, fully user configurable.
AETracker lets you track the inputs and outputs to all your AEM calls, and will show you exactly where errors are occurring.
Another very helpful use for AETracker is to sno0p other people's applications, you can get a full track of what AEM activity other applications are doing.
Enough market hype, here's the details.....
AETracker patches four traps, PostEvent, GetNextEvent, Close, and Pack8 (the AEM trap).
The first three are "housekeeping" patches for AETracker, mainly they let the CDEV and you talk to the INIT.
The PostEvent patch watches for the 'toggle' key sequence. You can set any single key + all modifiers as the toggle to turn AETracker on and off. Be SURE that you are not using that keystroke in another INIT or Application, since AETracker will eat the
event when it sees it, or alternately another INIT may already have
eaten it.
The PostEvent patch also looks for an event posted by the CDEV that tells it to reload the CDEV resources, that's how you can change AETracker's settings without rebooting the machine.
The GetNextEvent patch looks for flags that the PostEvent patch sets, and does things based on the flag, since GNE is memory moving safe and PostEvent ain't.
The Close patch is designed to keep the AETrack file open until you close it, despite ExitToShell trying to close the file when the app that was frontmost when it was created quits.
• Note: Because the Close patch exists, you have to _explicitly_ tell AETracker to turn itself off. That's why the flashing indicator in the menu bar exists, to let you know that AETracker is still running, so you don't end up with a lot bigger track file than you anticipated.
The Pack8 patch is where the real business happens;
When AETracker is toggled on, here's what happens....
A work file is opened, it will be named "AETrackXXXX" where
XXXX is Ticks at toggle time (creative, huh?). This file will always be
created in the Control Panels folder until you set a different directory with the button in the Control Panel.
• Note: In the unlikely instance that there is already a file named AETrack-XXXX in the control panels folder, AETracker will increment the first letter of the name until it can create the file, so you'll get things like BETrack-XXXX, CETrack-XXXX.
It may seem like that'll never happen, but I've done it twice during debugging.
You can change the file name by modifying 'STR ' resource -4064, but
whatever you change it to will still have the XXXX appended to it.
The Pack8 (AppleEvent manager) patch is enabled. Depending on the
myriad settings you can make, that patch will start writing data
to the work file.
AppleEvent traffic happens, and a nice log is written out.
The log will contain information about which routine was called, what application called it, when (in ticks) it was called, what parameters were passed to it, and what parameters were returned. Again, the amount of info in the log will depend on the settings you give the the Control Panel.
Also, a small black circle will flash in the right side of the menu bar, so you can tell that AETracker is tracking.
Here's a small sample, taken from a log of my AEObject sample
There are some machine cycles involved in all this. I'm head and tail patching Pack8, writing a lot of junk out to disk, and doing a lot of analysis of the data passed to the AEM on every AEM trap call.
I wrote AETracker in assembly to speed it up as much as I could, but
that still involves some time. And, since I don't know what you're debugging on, I had to stick with 68000 opcodes. Its fast, but not as fast as if it wasn't there at all.
Eventually you get all the info you need and you toggle AETracker off.
The work file is closed, the Close and Pack8 patches are deactivated,
and AETracker waits for another toggle.
You go read the track file (it's type TEXT) and are greatly impressed and
find all the AE bugs in your program, recode everything, go
golden master 3 weeks early, sell 1000000000 copies of your application, and
give me 10% royalties.
Well, hopefully the information will help.
The Settings
• Note: Changes to settings take effect as soon as the Control Panel is closed (you do NOT have to reboot!), so you can change your configuration and be testing again quickly.
Toggle Key
This is the key that turns AETracker on and off. It's a single key stroke with any combination of the 4 modifier keys down. Again, make sure that this key setting doesn't conflict with any other INITs (like SwitchApp, another fine RavenWare INIT) or whatever you have installed, since I zero out the event after I see it.
Tracking
These two radio buttons tell AETracker what application it should care
about. You have two choices, All Applications or Frontmost Only.
If you select All Applications, then AETracker records AE info happening
anywhere on your system.
If you select Frontmost Only, AETracker only will record AE action for
the application that is frontmost WHEN AETracker IS TURNED ON!
If that application subsequently goes into the background, AETracker
WILL STILL TRACK IT AND ONLY IT! I like this a lot.
Of course, if the application that you started AETracker in quits, it's PSN doesn't exists anymore. I am NOT checking for this, AETracker will just not be recording any information any more, even though it's still active.
Routine Selection
There are three radio buttons that let you set how much of the AEM stuff
going on you want to know about. The first button "Every Danged Thing" does just what it says. It will track information on all 53 AEM calls AND the 7 Object Support Library routines I know about.
This gives you a full log of information, and is REALLY neat.
The second, Limited, tracks only AESend and AEProcessAppleEvent. This is a good place to start, to give you a rough idea of what is going on in your system.
"Let Me pick 'em" introduces you to more radio buttons than you ever wanted to
see. But it also gives you a great deal of control. The dialog that comes up lets you specify exactly which calls you want to track, if you KNOW that there's a problem in AEGetKeyPtr you can track just that.
And if anyone can come up with a better way to do this than 50ish checkboxes,
let me know. But NOT popup menus, that would be worse, OK?
Information Selection
There are three information level settings you can pick.
"Minimum" gives you just routine name, application name, and tick count.
"More" gives you the above and information about the parameters passed to the AEM routine. It will also dump some of the data passed to some routines (AEPutParamPtr, for example). It dumps only 40 bytes of the data. Is that enough? Would you like to see more? Let me know.
"A great deal of information" head and tail-patches Pack8, and gives you everything that "More" does, plus reports on any errors and gives you details about the paramters returned from a call.
New for version 3 of AETracker is an additional check box under the Information Level radio buttons, titled 'Include calling routine name'.
When this box is checked, AETracker will attempt to find the MacsBug symbol for the routine that the AppleEvent call was made from. This can aid you a lot in finding out exactly where things are happening.
This may not always work, sometimes the routine has no name (as with routines in the Object Support Library) or AETracker may just not be able to deduce it. If that is the case, AETracker just doesn't print anything.
Supporting Players:
There is one resource you may want to play with, the FTYP resource. This is the creator of the track file I create. I have it set so the creator is MPW, you can change this to whatever you want to read the file in. The file will _always_ be created as a text file.
So why isn't the resource named CTYP? Because I'm goofy.
Wish I knew how:
How can I tell when an AEM routine is being called by the OSL? I'd like to ignore those, but since the OSL is linked into the application I can't differentiate OSL AEM calls from App OSL calls, since they come from the same zone. Any hints?
What are those unknown selectors the OSL is using????
I hope you find AETracker useful. I know I do, I have debugged several problems already because I wrote this.
Any comments, suggestions, or additions you have please send along to me, I'll try and implement them.
Please also send me the shareware fee ($5, c'mon).
C.K. Haun
January 1992
beta 1 Jan 92
• Initial release
beta 2 Feb 92
• Fixed small startup bug.
• Unrolled a few loops
beta 3 changes Mar 92
• Finally added a path selection button for the output file, argued with
the Alias Manager for a while about what a d*mned folder alias really means
• got rid of spurious alert when you cancel out of custom selector list
Version 2 changes April 92
• Changed some more code to make things go even faster
• Added tail-patch code. AETracker will now report result of calls, error and
parameter returns (Yaaaa!).
• Added cheezy help dialog.
• Projectorized the whole thing, for reasons that are unclear to me but I thought it
might be fun to play with Projector. I was wrong.
• Increased amount of data given from some calls.
Version 3 changes August 92
• External Control! Added Gestalt selector and 5 external routines
• Created 'AETracker Monitor', can be used by itself or as sample
code for your own interface
• Added some more data generation
• Added MacsBug symbol output.
• More speed changes
!NOTE! parsing strings (STR# -4064) MUST all be mod 4! I do this
for speed, if you edit those strings you MUST be sure they
are all evenly divisible by 4, or your results will be bad.
